Skip to main content

Send Push Notification

Show a notification on the phone or computer of a customer, even when the browser tab is closed, and let the customer answer by tapping a link in the notification. Each link continues the workflow on a different path.

This works with the standard web push technology of modern browsers. No app has to be installed and no phone number or e-mail address is needed; the customer only has to allow notifications once.

How it works​

  1. You build a diagram with a user input that has a field of the type Push subscription. This is the page where a visitor registers: it shows the button Enable notifications, the browser asks for permission and hands out a subscription, which is stored in a variable of the run.
  2. The activity sends the notification to the coupled browser.
  3. The visitor taps the notification or one of its buttons. The browser opens the link, and the workflow continues with the edge that belongs to it.

Set up your keys (once)​

Notifications are signed with a key pair (VAPID keys) that belongs to you, like the connection to Google Drive. You enter it in your account settings (/app/settings), section Push notifications:

  1. Click Generate key pair. Alternatively run npx web-push generate-vapid-keys and paste both values.
  2. Enter a contact in Contact (subject), your e-mail address as mailto:you@example.org or the address of your website. Push services may use it to reach you if your notifications misbehave.

The panel checks the keys while you type: the format, and that the private key belongs to the public key. Changes are saved at once. The private key is stored encrypted if the settings encryption key is configured on the server (see security); otherwise it is stored as plain text and the panel warns you.

When you start a diagram, your keys become secrets of that run: user.push.publicKey, user.push.privateKey and user.push.subject, see Secrets of the user. The Notification activity signs with them, and the registration field of the user input couples the visitor's browser with your public key. A diagram started by somebody else uses the keys of that user. Without keys the activity ends with activity error and the log says that push is not set up.

warning

A coupled browser is bound to the public key it was coupled with. If you replace your keys, every visitor has to couple again. Keep the keys stable while visitors are registered.

An administrator can additionally put a pair into the configuration of the server. It is used for diagrams of users who entered no keys:

application.properties
push.public-key=${PUSH_PUBLIC_KEY:}
push.private-key=${PUSH_PRIVATE_KEY:}
push.subject=${PUSH_SUBJECT:mailto:admin@example.org}

Requirements for the browser​

  • The page must be opened over https. localhost is allowed for tests.
  • The browser must support notifications (current Chrome, Edge, Firefox and Safari do; on iPhones the page has to be added to the home screen first).
  • The customer must not have blocked notifications for your site.

Build a diagram​

push diagram

  1. A user input with a variable push.subscription of the type Push subscription. The customer sees a button Enable notifications and presses it.
  2. A Notification activity. Set a title and a text. Variables are inserted with ${name}.
  3. A click response decision behind it. Every outgoing edge of the decision becomes a link in the notification, titled with the edge label.
  4. Connect the edges to the paths that should continue, e.g. confirm and reschedule.

A tap on a button, or on the notification itself, continues the workflow that waits behind the activity. If you add a timeout edge to the decision, it is taken when nobody answers in time, just like with e-mail.

Without a decision behind the activity the notification is one-shot: the workflow continues with next at once and the notification has no links.

Limits of notification buttons​

Browsers show only a few buttons, usually two, and some systems show none. Therefore:

  • At most two links are shown as buttons.
  • A tap on the notification itself opens the first link; links are ordered by the name of their edge.
  • Keep the labels short, they are cut off on small screens.

If more than two answers are needed, send the choices to a page, e.g. with a user input, and let the notification open it.

Parameters​

ParameterMeaning
push.titleTitle of the notification.
push.messageText of the notification. ${name} is replaced by the value of the variable.
push.subscriptionThe coupled browser. Preset to the variable ${push.subscription}, which a Push subscription field fills.
email.localeLanguage of the link titles, if the edge labels are translated. Defaults to en.

Usage​

  • next: the notification was sent (and, if a click response follows, the customer answered).
  • activity error: no browser is coupled, the coupled browser is unusable, push is not set up, or the push service refused the message. The reason is written to the application log of the task. A browser that has withdrawn its permission is reported as the user has to couple it again.
  • In a dry run nothing is sent; the log says how many links the notification would have had.

Privacy​

The notification text passes through the push service of the browser vendor (e.g. Google, Mozilla or Apple); it is encrypted for the browser, but the vendor knows that a message was delivered. Do not put confidential data into the text, send a link instead.

The subscription identifies a device. It is kept in the variables of the run, but cannot be used by anybody without your private key.